Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 090 / k9.arc / K9.DOC next >

Wrap

Text File | 1986-08-20 | 21.7 KB | 466 lines

K9.DOC documentation for K9 version 8/20/86 DPB /////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////// K9 is a multipurpose resident utility intended primarily to make life easier for programmers. It may be of some use to others as well, though user- friendliness has not been a design objective, especially in the documentation, which assumes a considerable understanding of DOS. K9 is named after Dr. Who's equally loyal, equally mindless, and equally squirrelly assistant. /////////////////////////////////////////////////////////////////////////// THIS SOFTWARE IS DISTRIBUTED UNDER THE SHAREWARE CONCEPT. The usual shareware "rules" apply. Anyone making regular use of K9 is requested to send $25 to: David P. Babcock 110 West Grant, #27-D Minneapolis MN 55403 Contributors' comments and suggestions are welcome via CompuServe (73307,2441) or by mail anytime. /////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////// Users of the Leading Edge Model D must not use K9 without reading HOT KEYS (below) carefully!! This information may be of use to other clone owners as well. /////////////////////////////////////////////////////////////////////////// INVOCATION ---------- K9 is meant to be invoked at boot time from a batch file. It's safest that way because it will be below any transient programs. K9 returns a DOS errorlevel of 0 if it loads successfully, and 1 if it finds itself already resident. It occupies 16K. A click may be heard from the speaker when K9 loads. This is from initialization of K9's microsecond timer and is not cause for concern. K9 requires DOS v. 2.0 or later. An attempt to load it under an earlier version of DOS will return an error message and a DOS errorlevel of 255. AUTOMATIC FUNCTIONS ------------------- The DOS keyboard buffer is expanded from 15 to 142 characters. The screen is turned off after 30 minutes of keyboard inactivity. The cursor may or may not remain visible. Any keystroke restores the screen. This function works on IBM machines or close compatibles and with most EGA cards. The DOS editor functions are extended to include F7 and F8 as recalling previous command lines. The most recent 256 bytes are maintained in a circular buffer that may be traversed backward via F7 or forward via F8. The least recent command line in the buffer may be missing one or more leading characters. The command is displayed as though the user had typed Escape, clearing the command line, and then the entry, but has not typed Enter. The DOS editor keys F1-F6 work as usual. The F7 and F8 keys can be extended to work within programs by setting the "W" switch to a non-zero value. This applies only to text entered via the DOS buffered input function, as in DEBUG, SYMDEB, or EDLIN. This input is maintained in a separate buffer, so that command lines will be recalled at the command prompt and text previously entered during the current execution of the program will be recalled while in the program. The program text buffer is cleared each time a program is loaded, and an attempt to use F7 or F8 if the buffer is empty will cause the function key to revert temporarily to its non- K9 definition. Thus, programs that define F7 and F8 for their own use can run without interference from K9, even with the "W" switch set, as long as they have not used the DOS buffered input function. A microsecond-resolution timer is started any time INT 21H is executed with AH=0FFh, and stopped when INT 21H is executed with AH=0FEh. The elapsed time in microseconds modulo 54925 (one timer tick) is displayed on the screen. The interrupt service routine preserves all registers and flags. Assuming the code to stop the timer is mov ah,0FEh int 21h the timing is from the first instruction after the first INT to but not including the "mov" instruction. The timer will be inaccurate if invoked while the speaker is operating. If it is suspected that the microsecond counter is overflowing, this can be tested by noting whether repeated invocations show instances of significantly longer elapsed times (indicating one or more timer tick interrupts from the hardware) in accordance with probability. COMMAND LINE PARAMETERS ----------------------- On loading, K9 will scan the command line tail for parameters. A parameter is any alphabetic character, with lower case mapping to upper case. The corresponding switch is set based on the character following the alphabetic character, as follows. All switches are defined in such a way that the machine behaves as much like a non-K9'd machine as possible if K9 is invoked with no command tail. following character parameter value ------------------- --------------- - 0 + 1 0..9 0..9 other 1 Any missing switch is set to 0. The following switches are defined: switch definition ------ ---------- A only [A]lt key sequences are hot. (See HOT KEYS below.) B A [B]/W monitor is being used with a color card. 0 = NO (DEFAULT) other = YES. C display time of day in upper right corner of screen. 0 = OFF (DEFAULT). 1 = display only at command prompt. 2 = display all the time. D implement [D]vorak keyboard. 0 = Qwerty (DEFAULT), any other=Dvorak. E pause the system and notify the user if a DOS [e]rrorlevel of at least the switch value is being returned by a non-resident process to its parent. (0 = OFF [default].) F see "K" switch. H park hard disk [H]eads at every command prompt. 0 = no (DEFAULT). 1 = yes. I On Alt-13, check to see if the interrupt vector table contains any addresses higher than K9 but below 0C8000h, and refuse to remove K9 if any such are found unless the segments are identical to what they were when K9 was loaded. 0 = yes (DEFAULT). This option makes it very unlikely that K9 will let itself be removed unless it is the highest item in memory, thus avoiding fatal corruption of the memory allocation chain. 1 = no. This allows for situations where orphan vectors may be in the table. With this option, the user must be much more careful not to try to remove K9 if there are any resident utilities above it, since the only check will be that there is no program running. K If non-zero, any K9 function request must be preceded by pressing a specific control [K]ey and function key simultaneously. The required control key is based on the K switch: 1 = right Shift key 2 = left Shift key 4 = Ctrl key 8 = Alt key The [F]unction key is based on the value of the F switch. If F is zero, F10 is selected. If F is any other value (X), then FX is selected. The F switch is meaningless if K is zero. L select [L]ist device for Alt-7 (1=LPT1:, 2=LPT2:, 3=LPT3:. DEFAULT (0) = LPT1:. P define Shift-[P]rtSc. 0 = BIOS-defined function (DEFAULT). 1 = save screen to disk. 2 = Shift-PrtSc has no function. In mode 1, the contents of the screen are saved in a file in the root directory of the current drive, whose name is the number of timer ticks since midnight in hex, with an extension of .SCR. Carriage return-line feed sequences are inserted, and any character less than 20h or greater than 7Fh is replaced with a space, so that the resulting file will dump to a printer without external processing. The file-naming method allows successive screen saves with the assurance that an ASCII sort by name of files generated during a calendar day will produce a chronological ordering. When the screen is saved, the name of the save file is written at the top of the screen. (The name of the most recent file name may be recovered by Alt-6/Ctrl-F (see below).) K9's usual procedure of restoring the screen that existed before its write operation on the next keypress operates here, too; but in this case the result can be startling if there was much screen activity since the screen save request was made. For eaxmple: you enter DIR for a lengthy directory, and in the middle of it request a screen save. This request is served, the save file name is flashed at the top of the screen (uselessly in this case), and the directory resumes, returning eventually to the command prompt. Your first keystroke here will recall the screen that was up when the save file message was flashed. Nothing is harmed, but the screen may look funny. (Of course Alt-8/Ctrl-H will clear it.) Q set AT keyboard typematic delay to Q [q]uarter seconds, in range 1-4. DEFAULT=2 quarter seconds (same as AT's boot value). This does not work on some compatibles, including the latest versions tested of the PC's Limited AT and the Sperry IT (even with an IBM keyboard), though the Sperry was tested only with the keyboard dipswitch in the "IT" position. The function is known to work on the IBM PC-AT, the Victor V286, the Eclipse ECS, and the Amax AT-3000. R set AT keyboard typematic repetition [r]ate to value as follows (DEFAULT=10.0 cps, same as AT's boot value): 1 = 30.0 cps (fastest allowed by AT) 2 = 20.0 cps 3 = 15.0 cps 4 = 10.0 cps (standard AT rate) 5 = 8.0 cps 6 = 5.5 cps 7 = 4.0 cps 8 = 2.7 cps 9 = 2.0 cps (slowest allowed by AT) S (for internal use) W Extend F7 and F8 to work [W]ithin programs. HOT KEYS -------- While resident, K9 is accessible to the user by the Alt key being held down while a decimal number is entered THROUGH THE NUMERIC KEYPAD, or, if the 'A' switch is zero, alternatively by Ctrl and a letter key. The latter possibility is offered only because some clones, notably Leading Edge, don't buy K9's method of distinguishing Alt-keypad combinations from anything else that generates the same ASCII value. If the "K" switch is non-zero, this request must be preceded by a control-key- plus-function-key combination (whose effect may be canceled by Alt-0). See the description of the "K" switch for a further description of this. If the "K" switch is non-zero and K9 is awaiting a request, the K9 logo will appear in the upper right corner of the screen (overriding the clock if a clock option is selected). If any K9 operation puts anything on the screen, the existing screen is first saved. It will be restored by the next keystroke other than the PrtSc key or either Shift key. If it is desired to restore the screen without having DOS or the current program read a keystroke, the Alt key is handy. Defined functions are as follows. The second key combination listed is allowed unless the 'A' switch is non-zero. ============================================================================== Alt-1/Ctrl-A: Display system status, consisting of: CPU (8086/88, 80186/188, 80286/88, or V20/V30) presence or absence of numeric coprocessor number of parallel ports number of serial ports equipment identification byte, per IBM definition total memory memory currently free (This tells how much memory is available for allocation by DOS. Note that this will always be 0 at the command prompt, since COMMAND.COM does not free memory until it starts a new process.) ROM date numeric coprocessor registers and flags, if a numeric coprocessor was found (The display is based on names given in the Intel manual and is straightforward. The only item that may not be immediately obvious is "remainder." This is the result of C0*4 + C3*2 + C1, which is the remainder left by an FPREM operation. Exception flags and pointers are not displayed.) ============================================================================== Alt-2/Ctrl-B: Invoke calculator. This may also be used for number base conversions. Alt-2 requires a numeric coprocessor, the author having written this function mainly to get the hang of writing for the 8087 in the first place. Arguments are given in RPN format. Operators are +, -, *, /, ** (power), SQR, SQRT, LN, LOG2, LOG10, PE (E to power), P2 (2 to power), AIN (arithmetic inverse, or unary minus), GIN (geometric inverse, or 1/x), SIN, COS, TAN, COT, SEC, CSC, DEG (degrees to radians), RAD (radians to degrees), ASIN, ACOS, ATAN, ACOT, and ! (factorial). Operators may be entered in upper or lower case. Operands may be entered in base 2, 8, 10, or 16, or standard or scientific floating- point format. Base identifiers (postfix) are: 2: 'B' or 'b'; 8: 'Q' or 'q'; 10 (default): 'D' or 'd'; 16: 'H' or 'h' or 'X' or 'x.' A leading hex literal is not allowed. Alpha constants recognized are PI and E. Arguments to trig functions are in radians (values in degrees must be converted with the DEG operator). Inverse trig functions do not allow negative arguments (if one is supplied, its absolute value is used), and results are in radians, which may be converted to degrees with the RAD operator. Output is displayed below the parameter line in scientific notation floating point with 15 digits of precision. On the line below this, binary, octal, decimal, and hexadecimal representations of the least significant 32 bits of the whole portion of the result are displayed, truncated toward 0, with the exception that if the result is outside the range -(2^63-1) .. 2^63-1, 0 is displayed. (0 may, of course, be a valid result--user examination is required.) The calculator may be exited by pressing the Enter key when it is awaiting input if nothing else has been entered. The truncation (rather than rounding) of the whole number portion can give the appearance of a conflict between the floating point output and the whole number output in certain calculations. The following was taken from the screen after an actual calculation: 30 deg sin sqr 30 deg cos sqr + 50000 * +5.00000000000000e+004 1100001101001111b 141517q 49999d C34Fh The trig identity is known to produce 1, which, multiplied by 50000, gives 50000. The floating point output does give this. However, the whole number is given as 49999. This is because, cos(30) being irrational, the actual calculation through the "+" may yield a result that is only approximately 1, because of rounding errors. In this case the identity yields a result that is less than 1, but by so little that multiplying it by 50000 gives 50000 exact to fifteen significant digits. To people, this is 50000. But to the numeric coprocessor, it isn't, and when the coprocessor is told to truncate this number, it does so. ============================================================================== Alt-3/Ctrl-C: Display the ASCII character set. Each character is displayed in hexadecimal, decimal, and character representations. ============================================================================== Alt-4/Ctrl-D: Display the state of all switches, and allow changes. The format for changes is the same as in the command tail at startup. ============================================================================== Alt-5/Ctrl-E: Toggle between Qwerty and Dvorak keyboard modes. (This may also be done via the 'D' switch in Alt-4/Ctrl-D, but allowance is made for the fact that the user who finds the wrong keyboard layout may not know where the 'D' key is.) ============================================================================== Alt-6/Ctrl-F: This copies the most recent file name generated by Shift_PrtSc to the DOS keyboard buffer. ============================================================================== Alt-7/Ctrl-G: Send commands to a printer using an extended Epson command set. Not all commands are supported by all Epson or Epson-compatible printers. The following commands are implemented. Those marked with an asterisk turn an option on if entered in upper case, and off if entered in lower case. The LPT number may be selected via the L switch. (A)ll [flush the printer buffer] * (B)old * (C)ondensed * (D)ouble strike * (E)lite [12 CPI instead of 10] (F)orm feed * (H)igh bit strip * (I)talics * (L)etter quality * (M)ini [form length = 8 1/2" instead of 11"] (N)ew [reset printer] * (O)ut [enable paper out sensor] * (P)roportional print (R)everse line feed * (S)kip over perf 1" * (T)wo [skip over perf 2"] * (U)nderline * (W)ide ["expanded"] * (Z)ero slash (~) Carriage return ============================================================================== Alt-8/Ctrl-H: Clear screen, do not home. ============================================================================== Alt-9/Ctrl-I: [Not used, to leave Alt-9 available to enter an ASCII Tab] ============================================================================== Alt-10/Ctrl-J: Terminate the current process and restore the interrupt vector table. This (usually) gets out of programs that are hung up in loops, or from which the user wants to escape but doesn't know how. It restores all interrupt vectors to whatever they were after K9 finished loading. Open file handles are not closed unless the particular DOS version or implementation takes care of it. A DOS errorlevel of 0 is returned. ============================================================================== Alt-11/Ctrl-K: Park hard disk heads. If this is attempted while not at the command prompt, the heads are left alone and a message appears. ============================================================================== Alt-12/Ctrl-L: [Not used, to leave Alt-12 available to enter an ASCII Form Feed] ============================================================================== Alt-13/Ctrl-M: Remove K9 from memory. This request will be refused if a program is running, or if the I switch is 0 and there are any interrupt vectors pointing above K9 but below segment 0C800h that are different from what they were when K9 was loaded. (This is to try to avoid the corruption that would occur if the user tried to remove K9 while memory was allocated above it.) Removal of K9 does not restore the AT keyboard typematic parameters if those were changed. ////////////////////////////////////////////////////////////////////////// APPLICATION NOTES ----------------- One user reports that K9 and DOSEDIT make a nice combination. DOSEDIT allows inter-line editing while in DOS, avoiding the somewhat awkward (at least to normal people) DOS editing keys. It appears to be in the public domain. Also, the original version of K9, circa July 1985, got along perfectly with SuperKey. K9 was then in C (it is now in assembler), but the logic of the keyboard intercepts is the same, so maybe K9 and SuperKey still get along. We would like to hear from someone on that. If used along with SideKick, K9 should be loaded after SideKick. This allows the F7 and F8 keys to work properly within SideKick's calculator, for users who prefer (or, for lack of a numeric coprocessor, must use) that calculator. K9 gets along fine with CodeSmith-86 (which helped bring it to life in the first place), SYMDEB, and DEBUG. We would be interested to hear of compatibility or lack thereof with other debuggers. ////////////////////////////////////////////////////////////////////////// TECHNICAL NOTES --------------- Of possible interest in multiple screen environments, or for heaven knows what other reasons: K9 uses BIOS to write to the screen, with the exception of the clock and the ASCII table, which write directly to the video buffer. K9 is written in assembler and assembled with Phoenix Technologies' LPASM, v. 2.00.